3-1 情景一：webpack+node.js服务端项目升级
升级场景概述
本节讨论一个具体的升级场景：将一个基于 Webpack 4 的 Node.js 服务端项目升级到 Webpack 5，同时升级 Node.js 版本以获得更好的性能和新特性支持。
这种升级在实际工作中非常常见——许多企业项目仍然运行在旧版本的 Webpack 上，安全补丁不再提供、新特性无法使用、依赖包之间的兼容性问题越来越多，升级是迟早要做的事情。
升级前的准备工作
1. 版本信息确认
升级前需要确认当前项目的技术栈版本：
| 依赖项 | 升级前 | 升级后目标 |
|---|---|---|
| Webpack | 4.x | 5.x |
| webpack-cli | 3.x | 5.x |
| Node.js | 12/14 | 18/20 |
2. 创建备份分支
git checkout -b feature/webpack5-upgrade
bash
确保所有变更都在独立分支上进行，出问题可以随时回滚。
3. 了解 Webpack 4 到 5 的重大变更
Webpack 5 相对于 4 有以下关键变化：
- 移除的功能：
CommonsChunkPlugin（改用optimization.splitChunks）、NamedModulesPlugin（默认行为）、NoEmitOnErrorsPlugin（默认行为） - 配置变化：
output.hashFunction默认改为xxhash64、devtool选项值调整 - Node.js polyfill 不再自动注入：如果代码中使用了
path、crypto、Buffer等 Node.js 模块，需要手动配置 polyfill 或添加resolve.fallback - 新的缓存机制：
cache.type: 'filesystem'提供持久化缓存 - 模块联邦（Module Federation）：新增的微前端支持
升级步骤
Step 1：升级 Webpack 核心依赖
npm install webpack@5 webpack-cli@5 --save-dev
bash
Step 2：升级相关 Loader 和 Plugin
根据项目实际使用的 Loader 和 Plugin 逐一升级：
# 查看过时的依赖
npx npm-check-updates -u
# 或手动升级
npm install babel-loader@latest css-loader@latest --save-dev
bash
Step 3：修改配置文件
移除已废弃的配置项：
// Webpack 4 写法（需要移除）
const CommonsChunkPlugin = require('webpack/lib/optimize/CommonsChunkPlugin');
// Webpack 5 替代方案
module.exports = {
optimization: {
splitChunks: {
chunks: 'all',
cacheGroups: {
vendors: {
test: /[\\/]node_modules[\\/]/,
name: 'vendors',
chunks: 'all'
}
}
}
}
}
javascript
处理 Node.js polyfill：
对于 Node.js 服务端项目，如果代码中使用了 Node.js 原生模块，需要配置 Webpack 5 不再自动注入 polyfill：
module.exports = {
resolve: {
fallback: {
path: false, // 服务端项目不需要 polyfill
crypto: false,
fs: false,
Buffer: false
}
}
}
javascript
如果是客户端项目使用了 Node.js 模块，则需要安装对应的 polyfill：
npm install path-browserify crypto-browserify --save-dev
bash
resolve: {
fallback: {
path: require.resolve('path-browserify'),
crypto: require.resolve('crypto-browserify')
}
}
javascript
Step 4：处理 Node.js 版本兼容
Webpack 5 要求 Node.js 10.13 以上版本，建议升级到 Node.js 18 LTS 或 20 LTS。
# 使用 nvm 切换 Node.js 版本
nvm install 20
nvm use 20
bash
Step 5：验证构建结果
# 执行构建
npx webpack --mode production
# 运行项目测试
npm test
bash
常见问题及解决方案
| 问题 | 原因 | 解决方案 |
|---|---|---|
Module not found: Error: Can't resolve 'path' | Webpack 5 不再自动注入 Node.js polyfill | 配置 resolve.fallback |
TypeError: Cannot read property 'getContext' of undefined | 某些 Loader 版本不兼容 Webpack 5 | 升级对应 Loader 到最新版 |
configuration.devtool should match pattern | devtool 配置值在新版本中变更 | 使用 eval-cheap-module-source-map 等新值 |
| 构建成功但运行时白屏 | TerserPlugin 配置变化 | 检查 optimization.minimizer 配置 |
升级收益
Webpack 4 升级到 5 的主要收益包括：
- 持久化缓存：
cache.type: 'filesystem'大幅提升二次构建速度 - 更好的 Tree Shaking：支持嵌套的 Tree Shaking 和内部模块的 Tree Shaking
- 模块联邦：支持微前端架构
- 资源模块：内置对图片、字体等资源的处理，不再需要
file-loader和url-loader - 构建性能提升：依赖预编译、缓存优化等带来更快的构建速度
参考资源
- Webpack 5 迁移指南 - 官方迁移文档
- Webpack 5 Changelog - 版本变更记录
↑